home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 May: Tool Chest / Dev.CD May 97 TC.toast / Sample Code / Toolbox / MacCalendar 1.1b1 / Read Me About MacCalendar < prev   
Encoding:
Text File  |  1997-03-20  |  6.9 KB  |  125 lines  |  [TEXT/ttxt]
  1. MacCalendar
  2.  
  3. 1.1b1
  4.  
  5. MacCalendar is a control strip module that displays a calendar when you click on it in the control strip.  The calendar display is configured using a separate application, MacCalendar Setup.
  6.  
  7. User-Level Installation and Use
  8.  
  9. To install the module:
  10.  
  11. 1. Drag the “MacCalendar” control strip module into the “Control Strip Modules” folder inside your System Folder.
  12.  
  13. 2. Restart.
  14.  
  15. 3. Run the “MacCalendar Setup” application to configure the control strip module.
  16.  
  17. Obviously the sample requires the Control Strip to be installed to be effective.
  18.  
  19. Building the Code
  20.  
  21. MacCalendar builds using the Metrowerks CodeWarrior 11 environment.  To build the code, open the “Metrowerks Build Script” AppleScript, run it, and select the “MacCalendar” folder.  The script with build the component projects in the appropriate order.
  22.  
  23. Packing List
  24.  
  25. The sample includes both a 68K project and PPC version of the “MacCalendar Setup” application, but only a 68K version of the control strip module.
  26.  
  27. The sample distribution contains the following files:
  28.  
  29. • Read Me About MacCalendar — This document.
  30.  
  31. • MacCalendar Setup.68K.µ — The 68K setup application project.
  32. • MacCalendar Setup.68K — A compiled version of the 68K setup application.
  33. • MacCalendar Setup.PPC.µ — The PPC setup application project.
  34. • MacCalendar Setup.PPC — A compiled version of the PPC setup application.
  35.  
  36. • MacCalendarSetup.c — Main source file for the setup application.
  37. • MacCalendarSetup.h — Constants that are shared between the setup application’s C and Rez source.
  38. • MacCalendarSetupIcons.rsrc — Icon resources for the setup application.
  39. • MacCalendarSetup.r — Other resources for the setup application.
  40.  
  41.  
  42. • MacCalendar.µ — The control strip module project.
  43. • MacCalendar — A compiled version of the control strip module.
  44.  
  45. • MacCalendar.c — Main source file for the control strip module. 
  46. • MacCalendar.h — Constants that are shared between the control strip module’s C and Rez source.
  47. • MacCalendarIcons.rsrc — Icon resources for the control strip module.
  48. • MacCalendar.r — Other resources for the control strip module.
  49.  
  50.  
  51. • DrawCalendar.h — The interface to a module for drawing calendars.
  52. • DrawCalendar.c — The implementation of the calendar drawing module.
  53.  
  54. • MacCalendarCommon.h — Declarations shared between the control strip module and the setup application.
  55.  
  56. • Metrowerks Build Script — An AppleScript tha builds the projects in the correct order.
  57.  
  58. Dynamic Preferences
  59.  
  60. Previous versions of this sample required a restart for preference changes to take effect. This version does not.  To achieve this, the sample shares a memory copy of the preferences between the module and the application.  This memory is in the form of a handle containing the settings.  [The data type for this, SavedSettingsHandle, is defined in “MacCalendarCommon.h”.]  This handle is published by the control strip module using Gestalt.
  61.  
  62. When the application launches, it looks up the settings using Gestalt and then clones the handle.  The application then works on the clone of the handle.  If you save your changes, the application copies the modified settings back into the module’s global handle.  The application also increments the “modCount” field of the settings.
  63.  
  64. In its idle routine, the module compares the “modCount” field of the settings to the value it last saved.  If they are different, it informs the Control Strip that it would like to be called to save settings.
  65.  
  66. When the Control Strip calls the module’s save routine, the module just writes out the settings handle and re-synchronises the “modCount” fields.
  67.  
  68. Design Limitations
  69.  
  70. 1. The calendar is displayed only while the mouse is held down — This seems inherent in the Control Strip interface: It is unclear who would “own” a window that behaved in a non-modal manner. Since there are a number of applications that provide a calendar in a window, this seemed like a reasonable limitation. Revising it so that the window was independent of the Control Strip might require changes to the Control Strip manager design.
  71.  
  72. 2. Black&white only — Adding color would be fairly simple, but it would increase the System Heap code size. Is it important? If so, what is the best way to configure the color?
  73.  
  74. 3. Configuration by a separate application — This minimizes interface-clutter (option-click to configure?). My own experience is that you set it once and then don't bother to set it again.
  75.  
  76. 4. Setup program font size selection — I didn't add a custom size value because it doesn't fit well within the popup-list control manager design. It would be easy to do (or I could do away with the popup-list and only use a dialog entry). The choices seem to be reasonable both for normal vision people and people who need large typefaces.
  77.  
  78. 5. Install and restart needed before the setup program runs — This just simplifies the program, and keeps it from running if the MacCalendar module is not installed. Note that the preferences are managed by the Control Strip manager: they are not stored in a separate file.
  79.  
  80. 6. Help via balloon help — Is help really needed for such a simple program?
  81.  
  82. 7. The control strip module requires System 7.5 or greater — This is because the module publishes its globals using Gestalt.  It’s much easier to do this using GestaltValue, which is only available under 7.5 or later.
  83.  
  84. Caveats
  85.  
  86. I have not looked into the international issues raised by this sample.  Primarily this sample is focused on how to build a control strip, not how to display a calendar.  Certainly providing user-configurable day name strings is a solution to the problem of how to display a calendar compactly, however I’m not sure whether it’s the best solution.
  87.  
  88. I also haven’t looked into LongDateTime issues.  I doubt this will ever be an issue for this sample.
  89.  
  90. Credits
  91.  
  92. If you find any problems with this sample, mail <DevSupport@apple.com> with “Attn: Quinn” as the first line of your mail and I’ll try to fix them up.
  93.  
  94. Written by Martin Minow, MACDTS.
  95. minow@apple.com
  96. AppleLink: MINOW
  97.  
  98. Updated by Quinn “The Eskimo!”
  99. Apple Developer Technical Support
  100. Networking, Communications, Hardware
  101. 19 Mar 1997
  102.  
  103. Version History
  104.  
  105. Version 1.0d1 - 1.0d6
  106. Martin Minow
  107. 1994
  108.  
  109. • See version notes in source.
  110.  
  111. Version 1.1b1
  112. Mar 1997, Quinn “The Eskimo!”
  113.  
  114. • Removed support for Think C and MPW.
  115. • Now uses the Rez compiler built in to Metrowerks.
  116. • Updated for CW 11 headers.
  117. • Removed the sample’s private “ControlStrip.h” header.
  118. • Include DTS standard disclaimer.
  119. • Rationalised header and source files.
  120. • Changed internal routines to “static”.
  121. • Now build without OLDROUTINENAMES and OLDROUTINELOCATIONS
  122. • The MacCalendar Setup application was modifying the “Control Strip Preferences” file directly!  Bad Martin, no biscuit!  I removed this bad behaviour by completely changisg the way preferences are shared between the application and control strip module.  As a side effect, we get dynamic preference changes.  Previous versions of this code forced you to restart to see preference changes.
  123. • Added build AppleScript.
  124. • I hate C’s "," operator!
  125.